Skip to content

feat(python-uv): add uv_compile_bytecode build option - #973

Merged
bnusunny merged 2 commits into
aws:developfrom
bnusunny:feat/python-uv-compile-bytecode-option
Nov 19, 2026
Merged

bnusunny merged 2 commits into
aws:developfrom
bnusunny:feat/python-uv-compile-bytecode-option

Conversation

@bnusunny

@bnusunny bnusunny commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Issue #, if available: Fixes #925

Description of changes

Adds a uv_compile_bytecode (bool) build option to the python_uv workflow, so callers can turn on the bytecode compilation added in #926. When it's on, the build runs compileall --invalidation-mode unchecked-hash with the target Python after uv pip install. The default is off. SAM CLI maps a UvCompileBytecode build property to it in aws/aws-sam-cli#9449.

  • A non-bool value fails with PythonUvBuilder:Validation - Build option uv_compile_bytecode must be true or false, got ....
  • The option also works for requirements.txt builds. Bytecode is compiled after install, and every manifest type goes through the same install step. Export options (uv_groups, uv_extras, uv_all_extras, uv_prune) on a requirements.txt build still fail.
  • UV_COMPILE_BYTECODE is honored when the build option isn't given. Since fix(python-uv): preserve compiled bytecode after packaging #926 the builder removes that variable from uv pip install (uv refuses it together with --no-compile-bytecode), so a user who set it got no .pyc at all. Now a truthy value turns on unchecked-hash compilation and is logged at INFO. Values are read the way uv reads them, case-insensitively: 1/true/t/yes/y/on turn it on, and 0/false/f/no/n/off leave it off. Any other value logs a warning and stays off. An explicit uv_compile_bytecode: false always wins.
  • DESIGN.md: a uv_compile_bytecode row in "Build options", a new "Bytecode" section, and the note about options on requirements.txt builds corrected.

Behavior change: builds with a truthy UV_COMPILE_BYTECODE now ship unchecked-hash .pyc files. Before #926 they shipped timestamp .pyc, which the Lambda runtime rejects after SAM normalizes timestamps (#924). Since #926 they shipped none.

Description of how you validated changes

  • Unit tests:
    • the option reaches the build action
    • it's allowed on requirements.txt builds
    • wrong types are rejected
    • an export option set together with bytecode on a requirements.txt build is still rejected
    • UV_COMPILE_BYTECODE true, false and invalid values
    • an explicit false wins over the variable
    • existing tests are isolated from a developer's own UV_COMPILE_BYTECODE
  • Integration tests with real uv (0.13.9) on a requirements.txt project:
    • no options: no __pycache__
    • uv_compile_bytecode: True, or UV_COMPILE_BYTECODE=1 with no option: six.*.pyc whose PEP 552 flags (header bytes 4-8, little-endian) are 1 (unchecked hash)
  • make lint and make black-check pass. python_uv unit tests: 168 passed (+53 subtests).

Checklist

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

@aws-sam-tooling-bot

aws-sam-tooling-bot Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

🧪 Hands-on test: 1 problem reproduced

Commit 02ea32f · build LambdaToolingHandsOn-NoDocker:ed9079ab-7324-4df2-8610-14f93149e8d1. The plan's scenarios ran on an isolated build host; a problem is reported only if it reproduced at least twice.

Merged with existing findings (1)
  • Bytecode enabled (UV_COMPILE_BYTECODE=1 or uv_compile_bytecode true) on a function with no manifest crashes the build with TypeError: evidence added to the review thread for lt-dab7fb4198b3

Scenarios

Scenario Planned check Result Runner's note
S1 Main path: uv_compile_bytecode true on a requirements.txt build produces unchecked-hash bytecode; without the option no… ✅ pass Head: uv_compile_bytecode true on requirements.txt build exits 0, artifacts include __pycache__, PYC_COUNT 1, __pycache__/six.cpython-311.pyc flags 1 (unchecked hash). Without the option PYC_COUNT 0.…
S2 UV_COMPILE_BYTECODE=1 with no option enables unchecked-hash bytecode and logs at INFO; explicit uv_compile_bytecode fal… ✅ pass Head: UV_COMPILE_BYTECODE=1 with no option logs INFO 'UV_COMPILE_BYTECODE=1 is set, compiling unchecked-hash bytecode for dependencies', PYC_COUNT 1, six .pyc flags 1. With explicit uv_compile_byteco…
S3 Env value parsing: case-insensitive falsy values stay off silently, unknown values warn and stay off, uppercase truthy … ✅ pass Head: OFF gives PYC_COUNT 0 and no log line; maybe gives WARNING "Ignoring UV_COMPILE_BYTECODE='maybe': expected one of 1, true, t, yes, y, on, 0, false, f, no, n, off" and PYC_COUNT 0; YES gives the…
S4 Reproduce static finding lt-dab7fb4198b3: bytecode enabled (by env var or option) on a function with no manifest. Suspe… ❌ fail Static finding lt-dab7fb4198b3 confirmed. Head, function with no manifest: UV_COMPILE_BYTECODE=1 and option uv_compile_bytecode true both fail with uncaught 'TypeError expected str, bytes or os.PathL…
S5 Validation and pyproject path: non-bool option is rejected; export option plus bytecode on requirements.txt is still re… ✅ pass Head: string 'true' rejected with "Build option uv_compile_bytecode must be true or false, got 'true'" (exit 2). uv_groups plus bytecode on requirements.txt rejected with 'Build options uv_groups nee…
S6 Bytecode with a separate dependencies_dir (incremental build path) reaches the artifacts dir; and the PR's own unit and… ✅ pass Head: build with dependencies_dir and bytecode true exits 0, ARTIFACTS include six.py and __pycache__, PYC_COUNT 1, flags 1. Unit tests: 178 passed, 53 subtests passed (the PR description says 168). …
Runner's notes in full
  • S1: Head: uv_compile_bytecode true on requirements.txt build exits 0, artifacts include __pycache__, PYC_COUNT 1, __pycache__/six.cpython-311.pyc flags 1 (unchecked hash). Without the option PYC_COUNT 0. Base: the option fails with 'Unknown uv build option(s): uv_compile_bytecode' (exit 2); no-option build matches head. A '.lock' file appears in artifacts on both head and base, so it is not caused by this PR.
  • S2: Head: UV_COMPILE_BYTECODE=1 with no option logs INFO 'UV_COMPILE_BYTECODE=1 is set, compiling unchecked-hash bytecode for dependencies', PYC_COUNT 1, six .pyc flags 1. With explicit uv_compile_bytecode false plus the env var: no INFO line, PYC_COUNT 0. Base: env var gives PYC_COUNT 0; option false is rejected as unknown.
  • S3: Head: OFF gives PYC_COUNT 0 and no log line; maybe gives WARNING "Ignoring UV_COMPILE_BYTECODE='maybe': expected one of 1, true, t, yes, y, on, 0, false, f, no, n, off" and PYC_COUNT 0; YES gives the INFO line and PYC_COUNT 1 with flags 1. No BUILD_ERROR.
  • S4: Static finding lt-dab7fb4198b3 confirmed. Head, function with no manifest: UV_COMPILE_BYTECODE=1 and option uv_compile_bytecode true both fail with uncaught 'TypeError expected str, bytes or os.PathLike object, not NoneType' (exit 2, reproduced 2/2 runs each). Traceback: _uv_config_from_options line 181 calls _project_name(None), which calls open(None) at line 204. Without either setting the build succeeds with ARTIFACTS ['app.py']. Base: env var case succeeds (ARTIFACTS ['app.py'], exit 0), so the env-var crash is a regression; option case fails there as unknown option.
  • S5: Head: string 'true' rejected with "Build option uv_compile_bytecode must be true or false, got 'true'" (exit 2). uv_groups plus bytecode on requirements.txt rejected with 'Build options uv_groups need a pyproject.toml project, but this build uses requirements.txt' (uv_compile_bytecode not listed, exit 2). pyproject.toml build with bytecode true exits 0, ARTIFACTS include six.py and main.py, PYC_COUNT 1, flags 1.
  • S6: Head: build with dependencies_dir and bytecode true exits 0, ARTIFACTS include six.py and __pycache__, PYC_COUNT 1, flags 1. Unit tests: 178 passed, 53 subtests passed (the PR description says 168). Integration tests -k bytecode: 4 passed, 0 skipped. No test covers the no-manifest crash from S4.

🤖 Automated hands-on test — not a review approval · model claude-opus-5.5 · Kiro kiro-cli 2.33.1 · build LambdaToolingHandsOn-NoDocker:ed9079ab-7324-4df2-8610-14f93149e8d1 · commit 02ea32f

History (4)
Commit Result When (UTC) Build
02ea32f Problems reproduced: Bytecode enabled (UV_COMPILE_BYTECODE=1 or uv_compile_bytecode true) on a funct… 2026-11-19 00:54 LambdaToolingHandsOn-NoDocker:ed9079ab-7324-4df2-8610-14f93149e8d1
d556e82 No problems observed 2026-11-18 19:13 LambdaToolingHandsOn-NoDocker:a1c01806-2b6b-4598-b4ea-e5675789b568
69d4735 No problems observed 2026-11-18 19:01 LambdaToolingHandsOn-NoDocker:6005e653-fd26-4c5d-9739-236ba068a0fb
1d1010f Problems reproduced: UV_COMPILE_BYTECODE=1 no longer produces bytecode; builds silently ship without… 2026-11-18 17:32 LambdaToolingHandsOn-NoDocker:450dc0cb-1b72-4234-881c-d321ab7a103f

@aws-sam-tooling-bot aws-sam-tooling-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧪 Hands-on test reproduced 1 new problem on commit 1d1010f. Commands and evidence are in the hands-on comment.

  1. [COMPATIBILITY] UV_COMPILE_BYTECODE=1 no longer produces bytecode; builds silently ship without .pyc where base produced timestamp .pyc · low · aws_lambda_builders/workflows/python_uv/packager.py:228

🤖 Automated hands-on test — not a review approval

@bnusunny
bnusunny requested review from licjun and vicheey November 18, 2026 17:43
@bnusunny
bnusunny marked this pull request as ready for review November 18, 2026 19:04
@bnusunny
bnusunny requested a review from a team as a code owner November 18, 2026 19:04
Adds a uv_compile_bytecode (bool) build option that turns on the
unchecked-hash bytecode compilation from aws#926. It also works for
requirements.txt builds. UV_COMPILE_BYTECODE is honored when the
option is not given; an explicit false wins.

Fixes aws#925
@bnusunny
bnusunny force-pushed the feat/python-uv-compile-bytecode-option branch from 69d4735 to d556e82 Compare November 18, 2026 19:05
@bnusunny bnusunny mentioned this pull request Nov 18, 2026
1 task done

@vicheey vicheey left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, LGTM.

Optional: a unit test for a falsy export option together with bytecode on a requirements.txt build, e.g. {"uv_all_extras": False, "uv_compile_bytecode": True}. Nothing covers the and value filter in export_options at the moment, and without it that build would fail with "need a pyproject.toml project".

@bnusunny
bnusunny enabled auto-merge (squash) November 19, 2026 00:47

@aws-sam-tooling-bot aws-sam-tooling-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review Results

Reviewed: c200cc7..02ea32f
Files: 4
Comments: 1

Comment on lines +174 to +175
export_options = {key: value for key, value in values.items() if key != "uv_compile_bytecode" and value}
if export_options and (not manifest_path or os.path.basename(manifest_path) != "pyproject.toml"):

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[BUG] Bytecode enabled with no manifest crashes the build with a TypeError
Before this change, any truthy uv_* option on a build with no manifest stopped at self._fail(...). Now that check runs only when export_options is non-empty. If uv_compile_bytecode is the only truthy value, the code goes on to the unchanged project_name = self._project_name(manifest_path).

That value can also come from a truthy UV_COMPILE_BYTECODE in the environment. When detect_uv_manifest finds nothing, __init__ sets manifest_path = None. _project_name(None) then calls open(None, "rb"), which raises TypeError. _project_name only catches OSError and ValueError, so the error is not handled.

The result: a user with UV_COMPILE_BYTECODE=1 set globally who builds a function with no pyproject.toml or requirements.txt gets an unhandled exception while the workflow is being built. Before this change, the build continued without dependencies. No build action uses the config when there is no manifest.

Fix: only call _project_name when it's needed (if values.get("uv_prune")). Alternatively, return UvConfig(compile_bytecode=...) before the project-name check when manifest_path is None and export_options is empty.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reproduced by a hands-on run 🧪

Commit 02ea32f · build LambdaToolingHandsOn-NoDocker:ed9079ab-7324-4df2-8610-14f93149e8d1 · scenario S4 · reproduced 2 times · exit codes 2, 2, 0

Commands:

. /work/scratch/venv-head/bin/activate; UV_COMPILE_BYTECODE=1 python /work/scratch/ho/build.py /work/scratch/ho/s4-head requirements.txt '{}'
. /work/scratch/venv-head/bin/activate; env -u UV_COMPILE_BYTECODE python /work/scratch/ho/build.py /work/scratch/ho/s4-head requirements.txt '{"uv_compile_bytecode": true}'
. /work/scratch/venv-base/bin/activate; UV_COMPILE_BYTECODE=1 python /work/scratch/ho/build.py /work/scratch/ho/s4-base requirements.txt '{}'

Evidence:

head, == env=1
WARNING aws_lambda_builders.workflows.python_uv.workflow: No UV-compatible manifest file found (pyproject.toml, requirements.txt). Continuing the build without dependencies.
INFO aws_lambda_builders.workflows.python_uv.workflow: UV_COMPILE_BYTECODE=1 is set, compiling unchecked-hash bytecode for dependencies
BUILD_ERROR TypeError expected str, bytes or os.PathLike object, not NoneType
EXIT=2

head traceback:
  File "/work/head/aws_lambda_builders/workflows/python_uv/workflow.py", line 181, in _uv_config_from_options
    project_name = self._project_name(manifest_path)
  File "/work/head/aws_lambda_builders/workflows/python_uv/workflow.py", line 204, in _project_name
    with open(pyproject_path, "rb") as pyproject_file:
TypeError: expected str, bytes or os.PathLike object, not NoneType

base, == env=1
WARNING ... No UV-compatible manifest file found ...
ARTIFACTS ['app.py']
PYC_COUNT 0
EXIT=0

🤖 Automated hands-on test — not a review approval

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed and reproduced on develop: with no manifest, _project_name(None) raised TypeError. Fixed in #976, which reads the project name only when uv_prune is set. With no manifest the build continues without dependencies, as before this PR.

@bnusunny
bnusunny merged commit 50b3733 into aws:develop Nov 19, 2026
125 checks passed
bnusunny added a commit that referenced this pull request Nov 19, 2026
…est (#976)

With uv_compile_bytecode (or a truthy UV_COMPILE_BYTECODE) and no
pyproject.toml or requirements.txt, _uv_config_from_options called
_project_name(None) and raised TypeError. Only uv_prune needs the project
name, so read it only then. The build now continues without dependencies,
as before #973.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

python_uv: UvConfig.compile_bytecode is never passed to uv, so the option has no effect

3 participants